Backport #4227 to 4.x: Let a reused engine discard the host objects its warmed caches hold - #4229

Backport of #4227 (fa0ee1354) to 4.x. Merge this only after #4227 has merged on main.

What it adds

Engine.Advanced.DiscardInterpreterCaches() is a new opt-in call for hosts that reuse an engine through CaptureGlobalSnapshot and RestoreGlobalSnapshot. A warmed call site keeps its last callee, and a warmed member-read site keeps its last receiver. On a pooled engine, that kept a finished request's host objects alive. One example is a delegate closing over the request's whole IServiceProvider, which is the Orchard Core engine-pool case that stays on 4.x.

The call drops the engine-owned handler trees (_functionDefinitions, _scriptStatementLists). It also releases the body tree of every definition it can reach:

• the cached definitions
• the realm's new Function cache, including the parked _dynamicCachedEnv
• functions bound on the global object or in global lexical bindings, including their _envReuse

Finally, it empties the ReferencePool. Two caches stay on purpose: _evaluatedScripts, so the next run re-caches at once, and _propertyKeyExpressions, which needs handler identity for #3142. The call refuses while an evaluation is in progress, the same refusal RestoreGlobalSnapshot makes. The design rationale and the list of what it does not reach are in #4227.

The only evaluation-path change is in JintFunctionDefinition.EvaluateConciseBodyAsync (async expression-bodied arrow). Its resume delegate now captures the body handler it started on instead of this, so the closure is the same size.

This is additive public API, so the 4.x release that carries it should be a minor version (4.17.0), not a patch.

4.x adaptations

• The public entry has no ThrowIfRetired or EnterHostCall, because neither exists on 4.x. Its guard is exactly 4.x's RestoreGlobalSnapshot guard (IsEvaluationInProgress || HasPendingAsyncOperations).
• 4.x has no EngineMemoryReport/HandlerTreeCacheReport. That XML-doc change and the main-only cache-count properties and ObjectPool.PooledCount that came along as context were dropped. ObjectPool.Clear() and ReferencePool.Clear() are ported as they are.
• Tests are converted to xUnit v3: [Theory]/[InlineData], and a DisableParallelization collection in place of [NonParallelizable]. Tasks.* becomes Advanced.RegisterPromise/ProcessTasks. The cache counts are read by reflection, as the existing GlobalSnapshotInternalsTests does, instead of through the memory report.
• Docs: 4.x has no docs/guide/performance.md or interpreter AGENTS.md. The pooling paragraph went into the README's "Reusing a configured engine" section. The gotcha edits went into the root AGENTS.md, minus the HandlerTreeCacheReport reference. The RestoreGlobalSnapshot and ResetCallStack XML docs are ported as they are.
• Public API baselines are updated for net10.0, net8.0, net462, netstandard2.0 and netstandard2.1, one line each.

Evidence

Unfixed 4.x. For this run, the product change was reverted and replaced by a no-op DiscardInterpreterCaches() stub so that the tests compile.

• InterpreterCacheDiscardTests: 8 of 16 fail on net10.0 and 8 of 16 fail on net472. That is every discard: true retention case (6), the re-cache test and the refusal test. All 6 no-discard controls pass, which shows the retention is real on 4.x.
• HostInterpreterCacheDiscardTests: 2 of 2 fail on each TFM.

With the fix, all of the above pass on both TFMs. As an ablation, I reverted only the concise-arrow capture: ASuspendedAsyncArrowResumesAcrossADiscard then fails with a NullReferenceException.

Full suites on this branch, Release:

No benchmarks were run. As noted on #4227, only the async concise-arrow path changed.

🤖 Generated with Claude Code